Skip to content

feat: add Codex-authored maintainer decision packets#358

Merged
steipete merged 10 commits into
openclaw:mainfrom
brokemac79:codex/decision-packets-v1
Jul 5, 2026
Merged

feat: add Codex-authored maintainer decision packets#358
steipete merged 10 commits into
openclaw:mainfrom
brokemac79:codex/decision-packets-v1

Conversation

@brokemac79

@brokemac79 brokemac79 commented Jun 23, 2026

Copy link
Copy Markdown
Contributor

Summary

  • lets Codex decide when a maintainer choice is genuinely required and return the exact question, rationale, options, recommendation, and likely owner
  • validates and persists that intent as a decision packet; deterministic code does not infer product judgment from labels or hard-coded heuristics
  • renders the decision clearly in review comments and blocks close/apply mutations when required intent is unresolved, malformed, stale, or inconsistent across paired items
  • refreshes or removes packet state during review, reconcile, replay, and apply paths

This keeps the useful persistence and maintainer-facing work from @brokemac79's proposal while moving the judgment to the model, where intent is understood best. Contributor authorship remains in the commit history and the changelog thanks @brokemac79.

Safety contract

maintainerDecision is required in the strict Codex output schema. A required decision must contain 1-3 options, exactly one recommendation, and an owner selected exactly from the proposed owner list. Missing or malformed intent fails closed before any GitHub mutation. Non-required decisions must use the canonical empty shape, so deterministic code cannot manufacture a decision from prose or labels.

Proof

  • full pnpm run check, including 668 core tests, 617 repair tests, repository coverage, lint, build, and formatting
  • focused decision/apply regressions: 37 tests passed
  • live OpenAI strict output-schema smoke with gpt-5.5; generated output accepted by the runtime parser
  • source-blind built-artifact behavior validation: exact intent persistence, public rendering, changed-input refresh, stale cleanup, and malformed-input fail-closed behavior all passed
  • fresh GPT-5.5 AutoReview: no actionable findings; patch correct (0.82 confidence)

Policy

VISION.md now records the durable rule: models propose maintainer decisions; deterministic code validates, persists, refreshes, and safely enforces them.

@clawsweeper

clawsweeper Bot commented Jun 23, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs changes before merge. Reviewed July 5, 2026, 3:41 AM ET / 07:41 UTC.

Summary
Adds Codex-authored maintainer decision packet parsing, rendering, durable JSON persistence, report frontmatter pointers, docs, schema coverage, and apply/replay/reconcile tests.

Reproducibility: yes. source-reproducible for the PR finding: the added malformed maintainer_decision branch records a kept-open result and continues before the normal skip helper stamps apply_checked_at. I did not run tests because this review is read-only.

Review metrics: 3 noteworthy metrics.

  • Patch surface: 13 files changed, 1453 additions, 24 deletions. The change spans schema, prompt, apply/replay/reconcile behavior, docs, and tests.
  • Generated-state writers: 3 write paths changed. apply-decisions, apply-artifacts, and reconcile now write or remove decision packet records.
  • Malformed skip coverage: 1 new test, 0 apply_checked_at assertion. The malformed-intent regression test proves no GitHub mutation but does not prove the report is marked as processed.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🐚 platinum hermit
Patch quality: 🦐 gold shrimp
Result: needs maintainer review before merge.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • [P2] Persist apply_checked_at for malformed maintainer-decision skips and add the regression assertion.

Risk before merge

  • [P1] Malformed maintainer_decision reports can be recorded as kept open without apply_checked_at, so future apply scans can repeatedly reprocess the same invalid report.
  • [P1] Decision packet JSON and decision_packet_* frontmatter are a new durable generated-state contract that maintainers and companion state consumers need to accept before merge.

Maintainer options:

  1. Persist malformed decision skips (recommended)
    Update the malformed maintainer_decision branch to stamp apply_checked_at and persist the report without making GitHub calls, then add a regression assertion.
  2. Accept rare repeated skips
    Maintainers may accept that malformed generated reports can consume a processed slot repeatedly if they expect schema validation to make this path effectively unreachable.
  3. Pause for state-contract changes
    If the packet schema, storage path, or stale cleanup semantics need a different contract, pause this PR and update those pieces before merge.
Copy recommended automerge instruction
@clawsweeper automerge

Special instructions:
Fix the malformed maintainer_decision branch in apply-decisions so it stamps apply_checked_at and persists the report without making GitHub calls; add a regression assertion in the existing malformed maintainer decisions test; run the focused node --test pattern for malformed maintainer decisions and decision packets.

Next step before merge

  • [P2] A narrow automated repair can persist the malformed-intent skip bookkeeping and extend the existing regression test.

Security
Cleared: No concrete security or supply-chain regression was found; the diff adds local JSON state writes and parser validation but no new dependencies, workflow permissions, or secret handling changes.

Review findings

  • [P2] Persist malformed decision skips — src/clawsweeper.ts:18050-18054
Review details

Best possible solution:

Persist terminal skip bookkeeping for malformed maintainer decisions, then land the packet contract once maintainers accept the generated-state schema and latest checks pass.

Do we have a high-confidence way to reproduce the issue?

Yes, source-reproducible for the PR finding: the added malformed maintainer_decision branch records a kept-open result and continues before the normal skip helper stamps apply_checked_at. I did not run tests because this review is read-only.

Is this the best way to solve the issue?

No, not quite; the feature shape is coherent, but malformed intent should still persist terminal skip bookkeeping so apply scans do not keep reprocessing the same bad report.

Full review comments:

  • [P2] Persist malformed decision skips — src/clawsweeper.ts:18050-18054
    This new malformed maintainer_decision branch records a kept_open result and then continues without calling markApplyChecked or writeReportMarkdown. Apply windows are ordered by apply_checked_at, so the same malformed generated report can stay at the front of later automatic scans and consume a processed slot every run; route this skip through the normal checked-state bookkeeping while still avoiding GitHub calls.
    Confidence: 0.86

Overall correctness: patch is incorrect
Overall confidence: 0.86

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against def41b3f889a.

Label changes

Label changes:

  • add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🐚 platinum hermit and patch quality is 🦐 gold shrimp. Replaced prior rating: 🐚 platinum hermit.
  • remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.

Label justifications:

  • P2: This is a normal-priority automation feature with a bounded but real apply-queue bookkeeping defect.
  • merge-risk: 🚨 automation: The diff changes review parsing, report rendering, apply/replay/reconcile state writes, and durable review comments.
  • merge-risk: 🚨 compatibility: The diff creates a new durable packet file contract and report frontmatter pointers consumed by companion maintainer tooling.
  • rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🐚 platinum hermit and patch quality is 🦐 gold shrimp. Replaced prior rating: 🐚 platinum hermit.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The provided PR context includes a built-CLI apply-decisions run against temp records with fake gh, showing packet creation, frontmatter pointers, stale-packet deletion, and pointer clearing.
  • proof: sufficient: Contributor real behavior proof is sufficient. The provided PR context includes a built-CLI apply-decisions run against temp records with fake gh, showing packet creation, frontmatter pointers, stale-packet deletion, and pointer clearing.
Evidence reviewed

Acceptance criteria:

  • [P1] node --test --test-name-pattern "malformed maintainer decisions|decision packet" test/clawsweeper.test.ts test/decision-packets.test.ts.
  • [P1] pnpm run check.

What I checked:

  • Repository policy read: AGENTS.md was read fully; its generated-state layout, apply-lane safety, and release-owned changelog guidance are relevant to this PR. (AGENTS.md:1, def41b3f889a)
  • Current main capability check: Current main has no decision-packet implementation or decision_packet frontmatter support; the only maintainerDecision match is an unrelated repair workflow helper. (def41b3f889a)
  • Decision packet persistence: The PR adds syncDecisionPacketRecord, which writes packet JSON, removes stale packet files, and updates decision_packet_path and decision_packet_sha256 frontmatter. (src/decision-packets.ts:267, 927668a34ea3)
  • Blocking apply bookkeeping defect: The added malformed maintainer_decision catch branch records a kept_open result and continues without calling the helper that stamps and persists apply_checked_at. (src/clawsweeper.ts:18050, 927668a34ea3)
  • Test gap: The malformed decision regression verifies no GitHub mutation and the apply result, but it does not assert that the report gains apply_checked_at. (test/clawsweeper.test.ts:435, 927668a34ea3)
  • Live PR state: GitHub reports the PR head as mergeable at 927668a; pnpm check was still in progress at the final live check while CodeQL jobs had passed. (927668a34ea3)

Likely related people:

  • steipete: Authored the latest PR commits that make decisions Codex-authored and has recent current-main apply/review policy work in the same area. (role: likely follow-up owner; confidence: high; commits: 0432e4d8e8bf, cdcb851924a7, f4bc90093196; files: src/clawsweeper.ts, prompts/review-item.md, VISION.md)
  • brokemac79: Has merged adjacent apply, review, state-scan, and dashboard automation work, including apply queue rotation that depends on apply_checked_at behavior. (role: recent area contributor; confidence: high; commits: 5bdf6f31c904, 542a35738928, 44f0d7ac1222; files: src/clawsweeper.ts, test/clawsweeper.test.ts, README.md)
  • vincentkoc: Git history ties the central apply/review report parsing and queue foundations to Vincent Koc, with recent current-main label reconciliation work nearby. (role: introduced behavior; confidence: medium; commits: ecbfc4fbfecb, 0d6aa5054c5a; files: src/clawsweeper.ts, .github/workflows/sweep.yml)
  • RomneyDa: The live PR is assigned to RomneyDa, and current-main history shows Dallin Romney split and maintained nearby apply/review test coverage. (role: assigned reviewer and adjacent test owner; confidence: medium; commits: 323f7bdf7236, 1c19987cde97, 8d8565bdea3b; files: test/clawsweeper.test.ts, test/apply-same-author-pair-close.test.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.
Review history (1 earlier review cycle)
  • reviewed 2026-07-03T17:05:44.291Z sha ce6591d :: needs maintainer review before merge. :: none

Comment thread src/decision-packets.ts Fixed
@brokemac79 brokemac79 force-pushed the codex/decision-packets-v1 branch from 62f755a to 6763870 Compare June 23, 2026 23:33
@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 🛠️ actively grinding The PR author has acted after the latest ClawSweeper review and work remains. labels Jun 23, 2026
@brokemac79 brokemac79 marked this pull request as ready for review June 23, 2026 23:45
@clawsweeper clawsweeper Bot added status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. and removed status: 🛠️ actively grinding The PR author has acted after the latest ClawSweeper review and work remains. labels Jun 23, 2026
@brokemac79 brokemac79 force-pushed the codex/decision-packets-v1 branch from 6763870 to 347418d Compare June 23, 2026 23:50
@brokemac79

Copy link
Copy Markdown
Contributor Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Jun 23, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@clawsweeper clawsweeper Bot added proof: sufficient Contributor real behavior proof is sufficient. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. P2 Normal priority bug or improvement with limited blast radius. merge-risk: 🚨 automation 🚨 Merging this PR could break CI, automerge, proof capture, label sync, or automation. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jun 23, 2026
@clawsweeper clawsweeper Bot added the merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. label Jun 29, 2026
@brokemac79 brokemac79 force-pushed the codex/decision-packets-v1 branch from 347418d to ce6591d Compare July 3, 2026 17:01
@RomneyDa RomneyDa self-assigned this Jul 3, 2026
@steipete steipete force-pushed the codex/decision-packets-v1 branch from ce6591d to 927668a Compare July 5, 2026 07:36
@steipete steipete changed the title Add maintainer decision packets feat: add Codex-authored maintainer decision packets Jul 5, 2026
@steipete steipete merged commit 232898f into openclaw:main Jul 5, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-risk: 🚨 automation 🚨 Merging this PR could break CI, automerge, proof capture, label sync, or automation. merge-risk: 🚨 compatibility 🚨 Merging this PR could break existing users, config, migrations, defaults, or upgrades. P2 Normal priority bug or improvement with limited blast radius. proof: sufficient Contributor real behavior proof is sufficient. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants